Risc World 3/Risc World 3.iso/SOFTWARE/ISSUE3/POWERBASE/DOCS/Ch12-Scrip

Text File | 2001-03-16 | 14KB | 269 lines

====================
Ch 12 − Script Files
====================

Powerbase incorporates a script language which lets you control many
features from a script file. Using script files you can automate jobs which
need to be done frequently, print jobs being the most obvious example.
Script files are plain text files (created with Edit, StrongEd etc.) and are
executed by dragging them to the Powerbase record window. All commands in a
script file must be in upper-case, preceded by “!”, and may be followed by
parameters (which are not case-sensitive), separated from the command by a
single space. A complete list of commands follows. Parameters in square
brackets are optional. Where commands simply control the status of options
switches (e.g. !CASE, !UPPER) the parameter is either ON or OFF.

!SCRIPT Since scripts are just text files there has to be a way for
Powerbase to recognise them. All script files must therefore start with a
line beginning with !SCRIPT. Prior to v.8 !SCRIPT POWERBASE was required;
you may still add POWERBASE but it is no longer necessary. You may use
!SCRIPT END as the last line of the file but this is also optional since the
script will terminate anyway when the end of the file is reached. You can
make the command “chain” another script file by following it with the name
of the new file, i.e. by using the form !SCRIPT <filename>. If you just give
a leafname Powerbase will look for it in the database’s PrintRes directory.
If it is stored anywhere else the full pathname must be supplied. This rule
applies to all script commands (e.g. !DELETE, !INCLUDE) which can take a
filename as a parameter. When a script file is dropped onto the record
window its name will be displayed with a request for confirmation that the
file is to be executed. To suppress this action use !SCRIPT QUIET as the
first line.

!COMMENT <string> may be used to insert comments in a script file. The rest
of the line is ignored.

!MESSAGE <string> will display a user-defined message in a small window to
keep the user informed of what’s happening during execution of a script.
!MESSAGE on its own closes the message window.

!SELECTION is used to select fields for inclusion in a report. If a filename
is given as a parameter Powerbase looks for a print Selection file of that
name and loads it, just as if you had double-clicked on it or dragged it to
the record window. (See !SCRIPT, above, for the interpretation of
filenames.) Alternatively, you may supply a comma-separated list of the tags
of the required fields and may include the record number, key and subfile
number by placing RECORD, KEY and SUBFILE, respectively, in the list. If you
supply no parameter at all the current selection will be cleared.

!PRINTOPTS <filename> loads a Print options file, setting the options just
as if the the file had been double-clicked or dragged to the record window.
Without a filename it sets the default options.

!SUBFILES <n>[,<n1>,<n2>...] selects the subfile(s) which will be searched
in order to create a report.

!CASE turns the Case switch on the Query panel ON and OFF.

!QUERY [filename\]<search formula> is used to print a report. It returns the
same result as entering a search formula in the Match window and clicking
Print. If you first issue a !DESTINATION FILE command you can use a list of
!QUERY commands to create a batch of reports as text files. If you omit the
optional filename each file will be created in PrintJobs using the search
formula (or part of it) as the filename. If you supply a name containing $
it is assumed to be a full pathname and will be used to create the file. Any
other name causes the file to be created in PrintJobs or in a subdirectory
(which must exist) of Print Jobs. Note the backslash between the filename
and search formula; this tells Powerbase where the one ends and the other
begins. !CASE  also affects the behaviour of this command if issued
beforehand.

!SAVE <filename> may be used to save a file which has been created in a
window. It is only useful after a !QUERY command for which the destination
is Window.

!CSV  [filename\]<search formula> is similar to !QUERY but produces a CSV
file instead. The CSV option settings are observed.  A prior !DESTINATION
command is unnecessary in this case.

!INCLUDE, !EXCLUDE, !CLEAR may conveniently be treated together. They have
the same effects as the controls on the Mark pane attached to the bottom of
the record window. !INCLUDE <key>[,<key>,<key>...] has exactly the same
effect as ticking the check box on the Mark pane for records with the
associated primary keys. !EXCLUDE (same syntax) has the same effect as
marking with a cross, which is what happens when the alternative option from
the pane’s pop-up menu is chosen. !CLEAR clears all marks. As an alternative
to a comma-separated list of keys you may supply a filename. The file should
be a plain text file with one primary key on each line. See !SCRIPT for the
interpretation of filenames.

                                - 54 -

!FORMAT <string> where <string> is Horizontal, Vertical, Label or Table sets
the print format. If any other parameter is used, or !FORMAT is issued by
itself, the Horizontal format is used.

!DESTINATION <string> where <string> is Window, File or Printer sets the
destination for report printing (see 3.1).  If File is used the report is
saved in PrintJobs unless a subsequent !QUERY command supplies an
alternative pathname (see above).

!EXPAND ON selects the the switch which causes fields to be expanded by
reference to a linked validation table. !EXPAND OFF (or just !EXPAND by
itself) deselects the switch.

!DATE turns date and time stamping ON and OFF.

!UPPER forces upper-case printing ON, normal upper/lower case printing
otherwise.

!HEADER, !FOOTER determine whether  header/footer information (see 3.10) is
printed on reports.

!FIRST when followed by ON causes the header to appear on the first page
only. (Footer information only appears on the final page anyway.)

!SHRINK determines whether surplus “white space” is removed from between the
columns of reports in Horizontal format.

!HEADINGS D causes descriptors to be used as field identifiers in a report.
!HEADINGS T, or without any parameter, causes tags to be used.

!TITLE <string> uses <string> as a title on subsequently printed reports.

!PAGE <n> sets the page length for reports to n lines. 64 is probably
correct for A4 (but see 3.10).

!SPACER <string> specifies the string to be used to separate columns of
printed data in reports using Horizontal or Table format (see 3.10).

!TEXTWIDTH <n> specifies the maximum width in characters for Memo and Text
block fields in reports.

!ORIENTATION <LANDSCAPE, SIDEWAYS> changes the paper orientation for
hard-copy printing from the default: !ORIENTATION PORTRAIT or UPRIGHT turns
it back again.

!HEADERFONT, !BODYFONT <fontname> set the fonts for headers and footers and
for body text in hard-copy printing. Names should be of the form
Homerton.Medium, Trinity.Bold.Italic etc. The font must, of course, be known
to the font-manager.

!FONTSIZE sets the size, in points, of the fonts used for hard-copy
printing.

!LMARGIN, !RMARGIN, !TMARGIN, !BMARGIN <n> set the print margins for
hard-copy printing. The units default to mm unless specified by appending
mm, in or pt to the number.

!PMARGINS cancels the margin settings in the Printer Setup window and uses
the printer driver’s default margins instead.

!LINESPACE <n> sets the spacing between the baseline of one line of printed
text and the next as a percentage of the font size. The default is 120%. For
Table format 150% looks neater.

!TABLE <columns>,<width>,<rows> sets up the number and width of blank
columns, and the number of blank rows at the end of the report, in Table
format. Column width is in mm but may be changed as for margins (see above).
You need not specify all the parameters; current values will be used if any
are omitted. You may, for example, specify 6 blank rows and nothing else by
using !LABEL ,,6. Note the commas.

!LABEL <n>,<w>,<h>,<str1>,<str2>,<s>,<su>,<bl>,ON/OFF determines the setup
for label-printing where: n=number of labels across the page, w and h are
the width and height of label (units may be specified as for margins and
column widths), str1 and str2 are the optional fixed first and last lines
and s=number of label at which printing on first page is to start. su and bl
are field tags. If field bl is blank then field su will be printed instead.
The final parameter specifies whether the primary key is to be printed on
the label. As with !TABLE you need only specify the values you wish to
change, but watch those commas!

!COPIES <n> specifies the number of copies to be printed

!SORT <n> specifies a column on which the report is to be sorted before
printing. The tag of a field included in the report may be specified instead
of a column number. The !SORT must appear before !QUERY in the script file.
It cannot be used when the output destination is File.

!IMPRESSION is used in conjunction with !QUERY to generate a report in

                                - 55 -

text-file format, allows you to insert Impression DDF* commands at the start
of the text-file. A script may, for example, execute a series of !QUERY
commands and the resulting files are to be all selected together and dragged
into an Impression document. To make each file go into a new frame you need
to make each begin with {nextframe}. This can be achieved by placing the
script command !IMPRESSION {nextframe} before the first !QUERY. You do not,
however, want {nextframe} to begin the first file created, or the Impression
document will have a blank frame on its first page. To suppress the effect
on the first file use: !IMPRESSION {nextframe} Not first. There must be a
space between the “}” and the “N”, but the “Not first” string isn’t case
sensitive.

!DELETE <key>[,<key>,<key>...] deletes record(s) having the supplied primary
key(s). As an alternative to the key or key-list you may supply the name of
a text-file containing the required keys, one to a line. The filename will
be interpreted as described above for !SCRIPT <filename>. The command can
delete records in any or all of the six subfiles, not just the current
subfile

!INSERT is the counterpart of !DELETE. Useful in similar circumstances. In
this case the command must occupy a line by itself and be followed by the
record to insert, one field to a line. It is the user’s responsibility to
ensure that the lines are not too long for the database fields into which
they are placed and that the number of lines following each !INSERT is the
same as the number of fields in the record. Don’t forget to leave blank
lines for empty fields!  Records will be inserted into the
currently-selected subfile.

!MOVE has the same syntax as !DELETE but moves records from their present
subfile to the next in sequence, regardless of the currently-displayed
subfile; e.g. a record in subfile 2 will be moved to subfile 3.

!CHANGE <field tag>,<old contents>,<new contents>[,<search formula>] allows
global changes to be made. The command functions like the Global changes
menu choice (see 2.5.5).

!OBEY <string> can be made to do anything which a *command can do. e.g.
!OBEY Delete <filename> will delete the named file. !OBEY <filename> will
attempt to *Run the file. By supplying the pathname of a Powerbase database
you can close the existing database and open a new one.

!KEY <index name> where the specified index name appears on the menu of
loaded indexes will make that the currently active index. If no parameter is
given the primary key index is selected.

!INDEX <tag>[,<tag>,<tag>...] constructs an index on the field whose tag is
first in the list and makes it the currently active index. If further tags
are supplied each is treated in exactly the same way. Using the Elements
database, for example, the command !INDEX Z,GP would index first on the
Atomic number (Z), then on the Group field (GP) with the Z index active. The
database is left with GP as the active index and a report of the whole
database shows the records ordered by Group but, within each group, the
records are in order of Atomic number; a sort within a sort. The whole field
(with spaces ignored) is used as the key unless you specify a shorter key by
placing a number before the tag, e.g. 5NAME for the leftmost five letters.

Powerbase “remembers” the names of the indices created by the most recent
!INDEX command and will delete them if you issue !INDEX with no parameters.

!FILTER <search formula> has the same effect as entering a search formula in
the Filter window. The Filter window isn’t opened but the Filter switch on
the keypad (or on the record screen if there’s a Filter switch there) is
turned on and the first matching record is displayed. !FILTER on its own
cancels the filter.

!STARTAT <tag> sets the field at which editing begins and places the caret
in that field. If no parameter is given, or if the designated field doesn’t
exist or isn’t writable, editing starts at the first writable field.

Requesting user input from script files
=======================================
This is best illustrated with an example. !FILTER GP=1 will use GP=1 as a
search formula. However, !FILTER Search formula? behaves quite differently.
A small window pops up saying “Search formula?” with a writable icon into
which you enter the formula then click OK or type Return. This applies to
all script commands. Instead of putting the parameter itself in the script,
supply a prompt followed by a question mark and the parameter and will be
requested and used with the command.  Why would you want to do this? You
might use a script to print a report in Table format but not always want the
same number of blank columns and rows. You can request these with !TABLE
Columns?,,Extra rows?,. Note the double comma (column width is not changed)
and the comma after “?”. Powerbase checks the parameter string for a
concluding “?” which, if found, causes the whole string to be treated as a
prompt. This is fine for commands like !TITLE which take only one parameter
but those which take multiple parameters need the concluding comma.

                                -56 -